Skip to content

Implement highlight/strikeout/wrap for code listings #965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 8 commits into from
Oct 17, 2025
Merged

Implement highlight/strikeout/wrap for code listings #965

merged 8 commits into from
Oct 17, 2025

Conversation

@DebugSteven
Copy link
Contributor

@DebugSteven DebugSteven commented Sep 2, 2025 •
edited
Loading

Summary

This PR implements new code block options for line highlighting, line striking, line wrapping, and showing line numbers. When the enable-experimental-code-block-annotations flag is enabled, code listings will have access to highlight, strikeout, and wrap properties forwarded in the render JSON.

User Experience

  • Lines listed in highlight appear with the same highlight seen in tutorials.
  • Lines listed in strikeout appear with a strikethrough line.
  • When wrap is present and greater than 0, code lines are soft-wrapped near the specified width.
  • When the showLineNumbers option is used on a code block, line numbers will render.
  • These options can be combined in the same code block.

Implementation Overview

  • Reads highlight: [Int]?, strikeout: [Int]?, wrap: Int?, and showLineNumbers (boolean) from RenderBlockContent.codeListing
  • Applies highlighting and strikethrough per line
  • Applies wrapping and line layout to the specified width per code block container

Dependencies

This PR depends on associated changes in swift-docc to actually render and handle the highlight, strikeout, wrap, and showLineNumbers options. The associated swift-docc PR is here: swiftlang/swift-docc#1287

Testing

Setup

Use the additional-metadata branches for swift-docc and swift-docc-render with the new highlight, strikeout, wrap, and showLineNumbers changes.
Rebuild documentation using swift-docc and the feature flag enable-experimental-code-block-annotations. Serve it using a local build of swift-docc-render.

How to Test

  1. In any code listing using ``` or by adding a code listing, add the highlight, `strikeout`, `wrap` and/or `showLineNumbers` options after the language (optionally) like this:
```swift, highlight=[1,3,4], strikeout=[2, 3], wrap=40
let a = 1
let b = 2
let c = 3
let d = 4
```
  1. Confirm highlighted lines and struck-through lines have the correct styling
  2. Confirm that wrapping is styled with the configured width.
  3. Confirm the show line number option shows line numbers.
  4. Confirm these options can be combined and are styled correctly.
  5. Verify the above behavior with and without a language token in the language line.

Checklist

  • Added tests
  • Ran npm test, and it succeeded
  • Updated documentation if necessary

These new options looks like the below:
Line highlighting, striking, wrapping, and line numbers in dark theme
Line highlighting, striking, wrapping, and line numbers in light theme

Compared to without these options:
Code example without options in dark theme

@DebugSteven DebugSteven mentioned this pull request Sep 2, 2025
Merged
3 tasks
@mportiz08
Copy link
Contributor

I haven't had a chance to check out the code in this PR yet, but I have a quick question about the styling for highlighted lines:

Would it maybe make sense to try and re-use the highlight color/style that are already used in tutorials? Example:
screenshot of tutorial with highlighted code

Or maybe you've already tried that already. The fluorescent orange color brings warning/deprecation semantics to my mind, which doesn't necessarily seem like the same idea.

@mportiz08
Copy link
Contributor

I'm also curious if you've considered adding the ability to configure line number display on/off with a custom setting like this?

I feel like it would be super useful in combination with the new wrapping feature to more easily distinguish between soft wrapped line vs purposeful newlines in the actual code.

marinaaisa
marinaaisa reviewed Sep 3, 2025
View reviewed changes
Copy link
Member

@marinaaisa marinaaisa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @DebugSteven , amazing work! thank you so much for your PR!

I left some suggestions to refactor the code a bit but everything else is great!

As @mportiz08 mentioned, I also think that you should consider changing the code of the highlighting to match the tutorials ones :)

Excited for this PR!

@heckj
Copy link
Member

heckj commented Sep 3, 2025

@marinaaisa @mportiz08 I was the source for the different coloration - I wanted an option that was significantly more like a highlighter so that it would pull more attention, especially in a an article context where a reader is more likely to be skimming, so that it drew their attention to the relevant sections quickly.

I totally get wanting to keep it consistent though, my biggest concern, especially with the dark mode viewing, is that the highlighting is too subtle - and only if you're really focused on the content will you capture that detail.

We also wanted to extend beyond what the tutorial offers - for example, the tutorial content doesn't display a deleted line, which is sometimes a critical piece of what's happening in an explanation, hence reaching for the strikeout flavoring.

@DebugSteven DebugSteven force-pushed the additional-metadata branch 2 times, most recently from 9b73675 to a74d9a1 Compare September 8, 2025 20:41
@DebugSteven
Copy link
Contributor Author

I got some feedback on the forums that people would like to see a way to highlight errors. David showed some examples where people indicate errors using plain text comments. Would it be acceptable to add an additional option for error highlighting with that orange color? Would you like error highlighting to have the same opacity as the highlighting for lines and in tutorials?

mportiz08
mportiz08 reviewed Sep 19, 2025
View reviewed changes
Copy link
Contributor

@mportiz08 mportiz08 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code looks pretty good to me so far right now—no obvious issues I'm noticing. I know that there is still some ongoing discussion on the syntax and JSON changes in the forums, but I think this PR is in good shape depending on how that discussion goes.

My only concern about the example screenshots is the one where content gets soft wrapped and the wrapped content starts at the very left edge of the container whereas I might expect it to start after the vertical space that is being used for the line numbers—pretty minor concern though and possibly could be addressed in the future (guessing it might be tricky to get it right).

Also, you may need to update the tests after merging in the latest main—we recently updated the testing library dependency which has some minor changes to the APIs for things like find, etc

@mportiz08
Copy link
Contributor

I got some feedback on the forums that people would like to see a way to highlight errors. David showed some examples where people indicate errors using plain text comments. Would it be acceptable to add an additional option for error highlighting with that orange color? Would you like error highlighting to have the same opacity as the highlighting for lines and in tutorials?

I don't have very strong opinions on this, but it looks like the highlight styling is already utilizing a CSS property for the color of the highlight, so hopefully this is something that can be easily extended for situations like that if we want to support it.

@d-ronnqvist
Copy link
Contributor

I got some feedback on the forums that people would like to see a way to highlight errors. David showed some examples where people indicate errors using plain text comments. Would it be acceptable to add an additional option for error highlighting with that orange color? Would you like error highlighting to have the same opacity as the highlighting for lines and in tutorials?

I don't have very strong opinions on this, but it looks like the highlight styling is already utilizing a CSS property for the color of the highlight, so hopefully this is something that can be easily extended for situations like that if we want to support it.

I don't necessarily suggest that we implement error highlighting right now but I want us to think about how this feature would be able to grow to support those kinds of highlights.

@heckj
Copy link
Member

heckj commented Sep 25, 2025

@swift-ci please test

@heckj
Copy link
Member

heckj commented Oct 8, 2025

@swift-ci please test

@DebugSteven
Add support for wrapping, highlighting, and striking out lines in cod…
4f1cd4a 
…e listings

* Implemented support for wrapping and highlighting individual lines

* Added strikethrough (strikeout) annotations

* Replaced specific line annotation styles with a unified `lineAnnotations` property

* Updated default values and tests to reflect new line annotation behavior
@QuietMisdreavus
Copy link
Contributor

@swift-ci Please test

mportiz08
mportiz08 reviewed Oct 10, 2025
View reviewed changes
Copy link
Contributor

@mportiz08 mportiz08 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome work! I think DocC users will love having these new capabilities :)

One minor visual thing I noticed is that the highlights can look a little less than ideal when the line numbers aren't enabled. (Looks great with line numbers enabled though!)

Screenshot 2025-10-10 at 4 46 15 PM

There isn't any spacing between the highlight edges and the content and the alignment between highlighted/non-highlighted lines is slightly off.

@heckj
Copy link
Member

heckj commented Oct 15, 2025

@swift-ci please test

mportiz08
mportiz08 reviewed Oct 15, 2025
View reviewed changes
@heckj
Copy link
Member

heckj commented Oct 16, 2025

@swift-ci please test

@heckj
Copy link
Member

heckj commented Oct 17, 2025

@swift-ci please test

@mportiz08
Copy link
Contributor

@swift-ci test

@mportiz08 mportiz08 merged commit b3b1f45 into swiftlang:main Oct 17, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mportiz08 mportiz08 mportiz08 approved these changes

@marinaaisa marinaaisa Awaiting requested review from marinaaisa

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@DebugSteven @mportiz08 @heckj @d-ronnqvist @QuietMisdreavus @marinaaisa